<HTML>
<HEAD>
<TITLE> Error Handling in CSPICE </TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">

<A NAME="top"></A>

<TABLE STYLE="text-align: left; margin-left: auto; margin-right: auto; width: 800px;" BORDER="0" CELLPADDING="5" CELLSPACING="2">
<TBODY>
<TR>
  <TD STYLE="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
  <DIV ALIGN="right">
    <SMALL><SMALL><A HREF="index.html">Index Page</A></SMALL></SMALL>
  </DIV>
  <B>Error Handling in CSPICE</B> </TD>
</TR>
<TR>
  <TD STYLE="vertical-align: top;">

<H2> Table of Contents
</H2>

<PRE>
   <A HREF="#Error Handling in CSPICE">Error Handling in CSPICE</A>
      <A HREF="#Abstract">Abstract</A>
      <A HREF="#CSPICE naming conventions">CSPICE naming conventions</A>
   <A HREF="#Introduction">Introduction</A>
   <A HREF="#Using CSPICE Error Handling">Using CSPICE Error Handling</A>
      <A HREF="#The First Thing You Should Know">The First Thing You Should Know</A>
      <A HREF="#What CSPICE Does About Errors, Automatically">What CSPICE Does About Errors, Automatically</A>
      <A HREF="#Changing What CSPICE Does About Errors">Changing What CSPICE Does About Errors</A>
      <A HREF="#Choosing Where the Error Messages Are Sent">Choosing Where the Error Messages Are Sent</A>
      <A HREF="#Choosing Which Error Messages to Write">Choosing Which Error Messages to Write</A>
         <A HREF="#Example 1">Example 1</A>
         <A HREF="#Example 2">Example 2</A>
         <A HREF="#Example 3">Example 3</A>
         <A HREF="#Example 4">Example 4</A>
         <A HREF="#Example 5">Example 5</A>
      <A HREF="#Choosing the Error Response Action">Choosing the Error Response Action</A>
      <A HREF="#Handling CSPICE Errors in Your Own Program">Handling CSPICE Errors in Your Own Program</A>
      <A HREF="#Testing the Error Status">Testing the Error Status</A>
      <A HREF="#Retrieving Error Messages">Retrieving Error Messages</A>
         <A HREF="#Getting the short message">Getting the short message</A>
         <A HREF="#Getting the long message">Getting the long message</A>
         <A HREF="#Getting the explanation for the short message">Getting the explanation for the short message</A>
         <A HREF="#Getting the traceback">Getting the traceback</A>
      <A HREF="#Resetting the Error Status">Resetting the Error Status</A>
      <A HREF="#Handling Errors Detected in Your Own Program">Handling Errors Detected in Your Own Program</A>
      <A HREF="#Signaling Errors">Signaling Errors</A>
      <A HREF="#Setting the Long Error Message">Setting the Long Error Message</A>
      <A HREF="#Using the RETURN Action and the CSPICE Function, return_c">Using the RETURN Action and the CSPICE Function, return_c</A>
      <A HREF="#Maintaining Traceback Information -- Checking In and Checking Out">Maintaining Traceback Information -- Checking In and Checking Out</A>
      <A HREF="#Clean Coding Using failed_c">Clean Coding Using failed_c</A>
         <A HREF="#Example 10">Example 1</A>
         <A HREF="#Example 20">Example 2</A>
      <A HREF="#Finding Out What the Current Error Handling Settings Are">Finding Out What the Current Error Handling Settings Are</A>
   <A HREF="#Concepts and Definitions">Concepts and Definitions</A>
      <A HREF="#About Errors">About Errors</A>
      <A HREF="#About Error Messages">About Error Messages</A>
         <A HREF="#The short error message">The short error message</A>
         <A HREF="#The explanation of the short error message">The explanation of the short error message</A>
         <A HREF="#The long error message">The long error message</A>
         <A HREF="#The traceback">The traceback</A>
         <A HREF="#The default message">The default message</A>
      <A HREF="#About Error Response Actions">About Error Response Actions</A>
   <A HREF="#Advanced Programming with Error Handling">Advanced Programming with Error Handling</A>
      <A HREF="#Using the CSPICE Functions failed_c and return_c">Using the CSPICE Functions failed_c and return_c</A>
      <A HREF="#Using the CSPICE routines chkin_c and chkout_c">Using the CSPICE routines chkin_c and chkout_c</A>
      <A HREF="#Using Multiple Settings of the Automatic Error Handling Features">Using Multiple Settings of the Automatic Error Handling Features</A>

</PRE>

<HR SIZE=3 NOSHADE>

<BR><BR>
<A NAME="Error Handling in CSPICE"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Error Handling in CSPICE
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Last revised on 2006 NOV 22 by N.J. Bachman.
<P>
 
<BR><BR>
<A NAME="Abstract"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Abstract
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   This Required Reading document details the use of CSPICE error handling
   facilities.
<P>
 
<BR><BR>
<A NAME="CSPICE naming conventions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> CSPICE naming conventions
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The CSPICE library is an implementation of the FORTRAN SPICELIB library
   in C. CSPICE is composed of C routines translated to C from FORTRAN by
   f2c and a set of wrapper functions which allow a more C native interface
   to the f2c'd routines.
<P>
 
<UL>
<TT>&#32;&#32;</TT> A routine name which ends in an underscore, "_", is an f2c translated
routine (pckopn_).
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> A routine name ending in and underscore c, "_c", is a wrapper routine
(<a href="../cspice/mxm_c.html">mxm_c</a>). It is strongly suggested that the user calls a wrapper routine
whenever available as opposed to the f2c translated counterpart.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> A routine name in all capital letters (SPKEZR) is a SPICELIB FORTRAN
routine.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Variables in routine calls with the suffix "_len" are the lengths of
particular strings in the argument list.
<BR><BR></UL>
<BR><BR>
<A NAME="Introduction"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Introduction
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Most of this information in this document is OPTIONAL reading, not
   ``required'' reading. To get started using CSPICE quickly, it suffices
   to read up through the section titled ``The First Thing You Should
   Know.''
<P>
 
   About the organization of this Required Reading document:
<P>
 
   The second chapter describes ``Using CSPICE Error Handling.'' We begin
   with brief descriptions of the error handling features, and many
   examples of their use.
<P>
 
   The third chapter describes ``Definitions and Concepts.'' This chapter
   provides a more detailed and complete discussion of the concepts used in
   describing the CSPICE error handling mechanism, but generally does not
   give examples. Here we define what we mean by ``errors,'' describe error
   messages and their use, and describe the possible error processing
   ``actions'' -- ways of responding to error conditions.
<P>
 
   The fourth chapter describes ``Advanced Programming With Error
   Handling''; that chapter discusses extension of the error reporting
   scheme to your own application code.
<P>
 
   The document covers the following topics:
<P>
 
<UL>
<TT>--</TT> How to make your program test whether a CSPICE routine has detected an
error, and how to find out what kind of error it was.
<BR><BR></UL>
<UL>
<TT>--</TT> How to direct CSPICE software to continue running after an error has
occurred, rather than stopping.
<BR><BR></UL>
<UL>
<TT>--</TT> How to select the messages you want to output when an error is detected.
<BR><BR></UL>
<UL>
<TT>--</TT> How to get a log of errors detected by your own application code.
<BR><BR></UL>
<UL>
<TT>--</TT> How to direct CSPICE software to send error messages to a file.
<BR><BR></UL>
<UL>
<TT>--</TT> How to get a traceback of your call chain when an error occurs in your own
code.
<BR><BR></UL>
   Error handling topics beyond the scope of this document:
<P>
 
<UL>
<TT>--</TT> Information about specific errors detected by CSPICE.
<BR><BR></UL>
<UL>
<TT>--</TT> How to take corrective action when an error is detected.
<BR><BR></UL>
<UL>
<TT>--</TT> How to debug programs that use CSPICE.
<BR><BR></UL>
<UL>
<TT>--</TT> How to determine whether to treat a condition arising in your own code as
an error.
<BR><BR></UL>
<UL>
<TT>--</TT> How to write code that performs the ``minimum possible'' amount of error
checking.
<BR><BR></UL>
   Before starting our discussion of how to use the CSPICE error handling
   facilities, let's briefly answer the question, ``Why perform error
   handling at all?'' Here are a few reasons:
<P>
 
<UL>
<TT>--</TT> It makes your program MUCH easier to debug. Most run-time diagnostics only
tell you about low-level types of errors such as arithmetic overflow,
attempts to divide by zero, or attempts to write protected memory
locations. These run-time errors may occur in very different locations from
the original coding mistakes causing them, so the original mistakes are
hard to find. CSPICE error handling helps bound the section of code where a
coding error is located, greatly simplifying the search for it.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Also, a good deal of understanding of a program without error handling is
often required to fix problems, since problems are diagnosed in low-level
terms, not conceptually: it's like the difference between being told that
the current through a certain wire in your television is zero, instead of
being told that your set isn't plugged in. Understand many mistakes may not
cause run-time diagnostics to be produced.
<BR><BR></UL>
<UL>
<TT>--</TT> Error handling makes your program much more robust. Your program can
respond to errors and continue execution in many cases, with CSPICE error
handling.
<BR><BR></UL>
<UL>
<TT>--</TT> It makes user-friendliness possible. When errors occur, your program can
retain control and present the problem to the user as you choose. Contrast
this to an abort with a run-time error message.
<BR><BR></UL>
<UL>
<TT>--</TT> It makes error handling portable and uniform across systems. CSPICE error
handling is accomplished using standard C. Different systems do not handle
run time errors in the same way.
<BR><BR></UL>
<BR><BR>
<A NAME="Using CSPICE Error Handling"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Using CSPICE Error Handling
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   This chapter tells you how to use most of the features of the CSPICE
   error handling mechanism. Many examples are given, but details are saved
   for the next chapter ``Concepts and Definitions.''
<P>
 
   The material in this chapter covers three areas:
<P>
 
<UL>
<TT>--</TT> Controlling CSPICE's automatic error handling features
<BR><BR></UL>
<UL>
<TT>--</TT> How to enable your own application to handle errors detected by CSPICE code
<BR><BR></UL>
<UL>
<TT>--</TT> How to use CSPICE error handling to respond to errors detected by YOUR OWN
code
<BR><BR></UL>
<BR><BR>
<A NAME="The First Thing You Should Know"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> The First Thing You Should Know
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The first thing to know about CSPICE error handling is, you don't HAVE
   to do anything to use it. As a default, when a CSPICE routine detects an
   error, CSPICE will print error messages to the default output device
   (the screen, on most systems), and then STOP.
<P>
 
   This capability is built into CSPICE software; you get it automatically
   when you link your program with CSPICE. No additional action of any kind
   is needed to make it work.
<P>
 
   If this behavior is adequate for your application, you don't need to
   read the rest of this document.
<P>
 
<BR><BR>
<A NAME="What CSPICE Does About Errors, Automatically"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> What CSPICE Does About Errors, Automatically
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   When a CSPICE routine detects an error (we call this ``signaling'' an
   error), the CSPICE error handling mechanism will write a set of
   descriptive error messages to the default output device, which is the
   terminal screen on most systems. The messages are:
<P>
 
<UL>
<TT>--</TT> A short, descriptive message.
<BR><BR></UL>
<UL>
<TT>--</TT> An expanded form of the short message.
<BR><BR></UL>
<UL>
<TT>--</TT> Optionally, a long message, possibly containing data.
<BR><BR></UL>
<UL>
<TT>--</TT> A ``traceback,'' showing the sequence of calls leading to the routine that
detected the error.
<BR><BR></UL>
<UL>
<TT>--</TT> A default message, informing the user that the error handling behavior is
adjustable.
<BR><BR></UL>
   After writing these messages, the error handling mechanism will halt
   execution of the program.
<P>
 
   See the section ``About Error Messages'' below for details.
<P>
 
<BR><BR>
<A NAME="Changing What CSPICE Does About Errors"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Changing What CSPICE Does About Errors
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   You can change the set of error messages written when an error occurs.
   You can re-direct the output to a file, or suppress it. You can choose
   to have your program continue after an detecting an error rather than
   stopping.
<P>
 
<BR><BR>
<A NAME="Choosing Where the Error Messages Are Sent"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Choosing Where the Error Messages Are Sent
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Suppose you want to have any error messages written to a file, rather
   than to the default output device (the screen, on most systems). You can
   do this by calling the CSPICE routine, <a href="../cspice/errdev_c.html">errdev_c</a>. The first argument
   should be 'SET'. The second should be the file specification.
<P>
 
   For example, to have error messages go to the file, ERROR.DAT, you could
   use the following code:
<P>
 
<PRE>
   /*
   Set the error output device for CSPICE to the
   file ERROR.DAT:
   */
   <a href="../cspice/errdev_c.html">errdev_c</a> ( "SET", lenout, "ERROR.DAT" );
</PRE>
   This call should precede calls to other CSPICE routines, except <a href="../cspice/erract_c.html">erract_c</a>
   and <a href="../cspice/errprt_c.html">errprt_c</a>. If your program has an initialization portion, this call
   should go there.
<P>
 
<BR><BR>
<A NAME="Choosing Which Error Messages to Write"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Choosing Which Error Messages to Write
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   By default, when an error is detected by a CSPICE routine, up to five
   different types of error messages are written. You can tell CSPICE's
   error handling mechanism to write any combination, including ``all'' and
   ``none'' of these messages.
<P>
 
   Change the set of written messages via a call to the CSPICE routine,
   <a href="../cspice/errprt_c.html">errprt_c</a>.
<P>
 
   The first argument should be 'SET'.
<P>
 
   The second argument is a list of message types that you want to ADD to
   the set of messages that currently are selected to be output when an
   error occurs.
<P>
 
   The keywords which may be used in the list:
<P>
 
<PRE>
   SHORT
   LONG
   EXPLAIN
   TRACEBACK
   DEFAULT
   ALL         ( write all messages )
   NONE        ( write no messages  )
</PRE>
   The list of message choices is read from left to right, with each word
   ADDING to the previous set of messages (except for the word NONE, which
   subtracts all of the messages from your selection).
<P>
 
   Some examples may help clarify this.
<P>
 
<BR><BR>
<A NAME="Example 1"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Example 1
</H3><P><BR><BR>
   Suppose that currently, the short message has been selected for output.
   To ADD the long message, make the call:
<P>
 
<PRE>
   /*
   Add the long message to the set selected for output
   when an error occurs:
   */
   <a href="../cspice/errprt_c.html">errprt_c</a> (  "SET", lenout, "LONG" );
</PRE>
   Now the short and long messages will be output if CSPICE detects an
   error.
<P>
 
<BR><BR>
<A NAME="Example 2"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Example 2
</H3><P><BR><BR>
   What if you want JUST the long message? Put the word NONE at the
   beginning of the list; this cancels the previous selection:
<P>
 
<PRE>
   /*
   Just output the long message when an error occurs:
   */
   <a href="../cspice/errprt_c.html">errprt_c</a> (  "SET", lenout, "NONE, LONG" );
</PRE>
<BR><BR>
<A NAME="Example 3"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Example 3
</H3><P><BR><BR>
   What if you want just the traceback and long message? Put the word NONE
   at the beginning of the list; this cancels the previous selection:
<P>
 
<PRE>
   /*
   Just output the long message and traceback on error:
   */
   <a href="../cspice/errprt_c.html">errprt_c</a> (  "SET", lenout, "NONE, TRACEBACK, LONG" );
</PRE>
<BR><BR>
<A NAME="Example 4"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Example 4
</H3><P><BR><BR>
   How about no messages?
<P>
 
<PRE>
      /*
      Don't output ANY CSPICE error messages on error:
      */
      <a href="../cspice/errprt_c.html">errprt_c</a> (  "SET", lenout, "NONE" );
</PRE>
<BR><BR>
<A NAME="Example 5"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Example 5
</H3><P><BR><BR>
   All messages?
<P>
 
<PRE>
      /*
      Output ALL CSPICE error messages on error:
      */
      <a href="../cspice/errprt_c.html">errprt_c</a> (  "SET", lenout, "ALL" );
</PRE>
   See the section ``About Error Messages'' below for details.
<P>
 
<BR><BR>
<A NAME="Choosing the Error Response Action"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Choosing the Error Response Action
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   CSPICE's default response to error detection includes halting the
   program. What if you don't want that?
<P>
 
   CSPICE's error handling mechanism allows you to choose one of several
   different error response ``actions.'' In almost all cases, the only
   reasonable alternative to the default action is RETURN. Briefly, the
   full set of choices consists of:
<P>
 
<DL><DT>
<B>
 DEFAULT
</B><BR><BR>
<DD>
 The action you start with, automatically. This is the same as ``abort''
(below), except that all of the error messages, including the
``default'' message, are written.<BR>
</DL>
<DL><DT>
<B>
 ABORT
</B><BR><BR>
<DD>
 Print messages and halts the program. With this action, you can select
the error messages that are written.<BR>
</DL>
<DL><DT>
<B>
 REPORT
</B><BR><BR>
<DD>
 Write messages and CONTINUE EXECUTION.<BR>
</DL>
   This action may be useful for debugging. Caution: Once an error has
   occurred, your program may not execute as expected.
<P>
 
<DL><DT>
<B>
 RETURN
</B><BR><BR>
<DD>
 Write messages, AFTER WHICH ALL CSPICE ROUTINES THAT DETECT ERRORS OR
CALL OTHER ROUTINES WILL RETURN IMMEDIATELY UPON ENTRY.<BR>
</DL>
   This is the action to use if you want to perform error handling for
   CSPICE errors in your own code.
<P>
 
<DL><DT>
<B>
 IGNORE
</B><BR><BR>
<DD>
 DO NOTHING in response to errors. No error messages will be output; the
CSPICE status functions <a href="../cspice/return_c.html">return_c</a> and FAILED will not indicate that an
error has occurred.<BR>
</DL>
   These choices are mutually exclusive; only one action can be in effect
   at a given time.
<P>
 
   You use <a href="../cspice/erract_c.html">erract_c</a> to set the error response action. The first argument
   should be 'SET'. The second argument should be one of the above choices.
   For example:
<P>
 
<PRE>
      /*
      Set the SPICELIB error response action
      to "RETURN":
      */
      <a href="../cspice/erract_c.html">erract_c</a> (  "SET", lenout, "RETURN"  );
</PRE>
<BR><BR>
<A NAME="Handling CSPICE Errors in Your Own Program"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Handling CSPICE Errors in Your Own Program
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   So far we've talked about how to control automatic reporting of errors
   detected in CSPICE routines.
<P>
 
   The automatic error reporting feature is meant to produce human-
   readable error diagnostic information. However, you may also wish to
   have your program respond to CSPICE errors.
<P>
 
   To do this, you will need to know about three more basic functions:
   testing and resetting the CSPICE error status, and retrieving CSPICE
   error messages.
<P>
 
<BR><BR>
<A NAME="Testing the Error Status"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Testing the Error Status
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   You use the CSPICE function, <a href="../cspice/failed_c.html">failed_c</a>, to tell if any SPICELIB routine
   has detected an error. <a href="../cspice/failed_c.html">failed_c</a> is a function which returns a boolean.
   It takes the `true' value, if any CSPICE routine has detected an error.
<P>
 
   For example, suppose you call the CSPICE routine, <a href="../cspice/rdtext_c.html">rdtext_c</a>, to read a
   line of text from a file. You want your program to test whether an error
   occurred on the read. You can write:
<P>
 
<PRE>
   /* Read a line from userfile.txt; check for errors: */
   <a href="../cspice/rdtext_c.html">rdtext_c</a> ( "userfile.txt", line_len, line, &amp;eof );
 
   if ( <a href="../cspice/failed_c.html">failed_c</a>() )
   {
      return;
   }
</PRE>
   If you're used to routines that have error arguments, you might note
   that the code is similar to what you would write if FAILED were an
   output argument for <a href="../cspice/rdtext_c.html">rdtext_c</a>, instead of a function.
<P>
 
   However, there are a number of advantages to the CSPICE method, one of
   which is that if you don't wish to write any error handling code to
   handle CSPICE errors, you don't have to, and you'll still get helpful
   error messages automatically. Also, if you use CSPICE error handling in
   your own code, you don't need error arguments, which makes for simpler
   code.
<P>
 
<BR><BR>
<A NAME="Retrieving Error Messages"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Retrieving Error Messages
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   CSPICE provides routines to retrieve the error messages generated
   whenever a CSPICE routine detects an error.
<P>
 
   This feature is useful for two reasons. First, if you want your program
   to take different actions depending on what error occurred, it gives
   your program a way to find out. Second, if you want to generate your own
   error reports instead of using those generated by CSPICE, you need to be
   able to retrieve the information CSPICE has generated about the error.
<P>
 
<BR><BR>
<A NAME="Getting the short message"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Getting the short message
</H3><P><BR><BR>
   Because of its brief format, the short message is the one to use in your
   code in any logical tests you might want to do.
<P>
 
   To retrieve the short error message, call <a href="../cspice/getmsg_c.html">getmsg_c</a> or getsms_. For
   example:
<P>
 
<PRE>
   /*
   Call <a href="../cspice/prompt_c.html">prompt_c</a> to prompt the user for the name of file
   to read from.  Read a line from it. Check for errors:
   */
   <a href="../cspice/prompt_c.html">prompt_c</a> ( "Enter file name &gt; ", file_len, file );
 
   <a href="../cspice/rdtext_c.html">rdtext_c</a> ( file1, line_len, line, &amp;eof );
 
   while ( !<a href="../cspice/eqstr_c.html">eqstr_c</a> ( file, "" ) )
   {
</PRE>
<PRE>
      if ( <a href="../cspice/failed_c.html">failed_c</a> () )
      {
         /*
         An error occurred.
         Find out what the short message was:
         */
 
         <a href="../cspice/getmsg_c.html">getmsg_c</a> ( "SHORT", shrtms_len, shrtms );
 
         if (    <a href="../cspice/eqstr_c.html">eqstr_c</a>( shrtms, "SPICE(NOFREELOGICALUNIT)" )
              || <a href="../cspice/eqstr_c.html">eqstr_c</a>( shrtms, "SPICE(TOOMANYFILESOPEN)"  )  )
         {
            /*
            We won't succeed in reading any file.
            So, quit.
            */
            return;
         }
         else
         {
            /* Get name of a different file: */
            <a href="../cspice/prompt_c.html">prompt_c</a> ( "Enter file name &gt; ", file_len, file );
         }
      }
   }
</PRE>
<BR><BR>
<A NAME="Getting the long message"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Getting the long message
</H3><P><BR><BR>
   The long error message and traceback aren't useful for program logic,
   but you may want them if you're going to produce error reports in your
   own format.
<P>
 
   To get the long error message, call <a href="../cspice/getmsg_c.html">getmsg_c</a> or getlms_. For example,
<P>
 
<PRE>
   <a href="../cspice/rdtext_c.html">rdtext_c</a> ( file, line_len, line, &amp;eof );
 
   if ( <a href="../cspice/failed_c.html">failed_c</a>() )
   {
      /*
       Get long message and output it.
      */
      <a href="../cspice/getmsg_c.html">getmsg_c</a> ( "LONG", longms_len, longms);
      printf  ( "%s \n", longms );
   }
</PRE>
   The argument supplied to <a href="../cspice/getmsg_c.html">getmsg_c</a> should be declared char *.
<P>
 
<BR><BR>
<A NAME="Getting the explanation for the short message"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Getting the explanation for the short message
</H3><P><BR><BR>
   The CSPICE routine expln_ can obtain a line of text explaining each
   CSPICE short error message. This text is an expansion of the short error
   message, since the short message is frequently abbreviated.
<P>
 
   Here's an example:
<P>
 
<PRE>
   /*
   After this call, EXPL will take the value:
 
   "Invalid Radius--Equatorial or Polar Radius is Zero"
   */
 
   expln_( "SPICE(ZERORADIUS)", expln, 17L, expln_len);
   printf ( "%s \n", expln )
</PRE>
<BR><BR>
<A NAME="Getting the traceback"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Getting the traceback
</H3><P><BR><BR>
   Two ways of getting the traceback are provided in CSPICE:
<P>
 
<UL>
<TT>--</TT> You can call the routine qcktrc_ which returns a character string
containing a traceback. Specifically, the string contains a list of module
names, separated by arrows. The first name in the string is the name of the
highest level module in the active call chain that has ``checked in.''
<BR><BR></UL>
   Example: Suppose MAIN has called SUBA, which in turn has called SUBB.
   The following code is in SUBB:
<P>
 
<PRE>
 
   /*
   Get traceback.  After the call to qcktrc_,
   TRACE should have the value,
 
   "MAIN --&gt; SUBA --&gt; SUBB"
   */
 
   qcktrc_(trace, trace_len);
 
   printf ( "%s \n", trace );
</PRE>
<UL>
<TT>--</TT> You can find out how many routines are in CSPICE's traceback representation
by calling TRCDEP (``traceback depth''), and then extract any given name
from the traceback representation by calling trcnam_.
<BR><BR></UL>
   For example, you could print out the names of all of the modules in the
   active call chain with the following code:
<P>
 
<PRE>
   trcdep_ ( depth );
 
   for ( i=0; i&lt; depth; i++ )
   {
      trcnam_( i , name , name_len);
      printf ( "%s \n", name );
   }
</PRE>
<BR><BR>
<A NAME="Resetting the Error Status"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Resetting the Error Status
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   If your program encounters a recoverable error, you may wish to have it
   report the error and continue processing.
<P>
 
   An example would be the case where you have an interactive program that
   prompts the user for the name of a file to read. Your program uses the
   CSPICE function <a href="../cspice/rdtext_c.html">rdtext_c</a> to read the file. If the file isn't found,
   <a href="../cspice/rdtext_c.html">rdtext_c</a> signals an error. The inability to locate the file need not
   stop the program; your program could just display a message saying the
   file wasn't found and ask for another file name.
<P>
 
   The problem here is that the CSPICE functions <a href="../cspice/failed_c.html">failed_c</a> and <a href="../cspice/return_c.html">return_c</a> will
   return the `true' value after <a href="../cspice/rdtext_c.html">rdtext_c</a> signals the error, so any code
   whose logic depends on the value of those functions will behave as if an
   error has occurred, even though the error was recoverable. To solve this
   problem, CSPICE provides the routine, <a href="../cspice/reset_c.html">reset_c</a>, which ``resets'' the
   error handling mechanism, so that it acts as if no error had occurred.
   Calling <a href="../cspice/reset_c.html">reset_c</a> has the following effects:
<P>
 
<UL>
<TT>--</TT> The CSPICE function <a href="../cspice/failed_c.html">failed_c</a> will return the `false' value until another
error is signaled.
<BR><BR></UL>
<UL>
<TT>--</TT> The CSPICE function <a href="../cspice/return_c.html">return_c</a> will return the `false' value until another
error is signaled.
<BR><BR></UL>
<UL>
<TT>--</TT> <a href="../cspice/getmsg_c.html">getmsg_c</a>, getsms_, and getlms_ will return blank strings.
<BR><BR></UL>
<UL>
<TT>--</TT> The traceback routines will show a traceback of the current active call
chain, not the active call chain at the time of the last error.
<BR><BR></UL>
   When your program detects a recoverable error, it should fetch the error
   messages, call <a href="../cspice/reset_c.html">reset_c</a>, then complete its response to the error. The
   diagnostic messages must be fetched before RESET is called. RESET should
   be called before other SPICE routines are called, because these routines
   may return upon entry while an error condition exists.
<P>
 
<BR><BR>
<A NAME="Handling Errors Detected in Your Own Program"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Handling Errors Detected in Your Own Program
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   When you use CSPICE, you can use the error handling mechanism to respond
   to errors detected by your own code, as well as by CSPICE code.
<P>
 
   Some of the capabilities that you get with CSPICE are:
<P>
 
<UL>
<TT>--</TT> You can signal errors and have your error messages output to a chosen
device, without writing code to do the output.
<BR><BR></UL>
<UL>
<TT>--</TT> You can get a traceback of your own call chain, which can be retrieved at
any time, not just when an error occurs.
<BR><BR></UL>
<UL>
<TT>--</TT> You can control how your program behaves when it encounters an error, just
as when CSPICE encounters one.
<BR><BR></UL>
<UL>
<TT>--</TT> You can use <a href="../cspice/failed_c.html">failed_c</a> as a global status indicator, not just for CSPICE
code.
<BR><BR></UL>
<UL>
<TT>--</TT> You can use <a href="../cspice/return_c.html">return_c</a> to prevent your routines from executing when an error
condition exists, thereby obviating the need to test FAILED after each call
to a subroutine.
<BR><BR></UL>
   In the following sections we explain:
<P>
 
<UL>
<TT>--</TT> How to ``signal'' (indicate) an error condition
<BR><BR></UL>
<UL>
<TT>--</TT> How to create error messages
<BR><BR></UL>
<UL>
<TT>--</TT> How to use the RETURN error response action and the CSPICE function
<a href="../cspice/return_c.html">return_c</a> to help your program handle recoverable errors
<BR><BR></UL>
<UL>
<TT>--</TT> How to use the CSPICE routines <a href="../cspice/chkin_c.html">chkin_c</a> and <a href="../cspice/chkout_c.html">chkout_c</a> to create a traceback
of your own subroutine calls
<BR><BR></UL>
<UL>
<TT>--</TT> How to code using <a href="../cspice/failed_c.html">failed_c</a> so as to reduce the amount of error checking you
need in your code
<BR><BR></UL>
<UL>
<TT>--</TT> How to retrieve the settings of the error output device, error response
action, and error message selection
<BR><BR></UL>
<BR><BR>
<A NAME="Signaling Errors"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Signaling Errors
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   A routine calls <a href="../cspice/sigerr_c.html">sigerr_c</a> to signal an error condition to the CSPICE
   error mechanism.
<P>
 
   When <a href="../cspice/sigerr_c.html">sigerr_c</a> is called, all of the types of error messages that have
   been selected for automatic output are written out, and CSPICE takes
   whatever additional actions are required by the current setting of the
   error response ``action.''
<P>
 
   <a href="../cspice/sigerr_c.html">sigerr_c</a> takes one input argument, a short (25 character maximum) error
   message. This message will be output if the ``short message'' has been
   selected for output. It is strongly recommended that your code supply a
   descriptive (at least non-blank) error message when it calls <a href="../cspice/sigerr_c.html">sigerr_c</a>.
<P>
 
   The short message, if used, indicates the type of error which occurred,
   so the program can respond appropriately.
<P>
 
   A capability exists to set a long, human-readable, error message. The
   next section discusses setting the long message.
<P>
 
   Here's an example in which the routine, DACOSH, signals an error.
<P>
 
<PRE>
      /*
      DACOSH computes an arc hyperbolic cosine of X; X must
      be greater than or equal to 1 to be in the domain of
      DACOSH.
 
      Check that x &gt;= 1.
      */
 
      if ( x &lt; 1. )
         {
         <a href="../cspice/setmsg_c.html">setmsg_c</a> ( "DACOSH: Invalid argument, X is less than one." );
         <a href="../cspice/sigerr_c.html">sigerr_c</a> ( "SPICE(INVALIDARGUMENT)"                        );
         return;
         }
</PRE>
   You may note a call to the routine <a href="../cspice/setmsg_c.html">setmsg_c</a> precedes the call to
   <a href="../cspice/sigerr_c.html">sigerr_c</a> as <a href="../cspice/setmsg_c.html">setmsg_c</a> sets the long error message. setmsg_c is discussed
   in the next section, but we'll note here that if you wish to call
   <a href="../cspice/setmsg_c.html">setmsg_c</a>, it should be called BEFORE calling <a href="../cspice/sigerr_c.html">sigerr_c</a>, since sigerr_c
   causes the current long error message to be output.
<P>
 
<BR><BR>
<A NAME="Setting the Long Error Message"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Setting the Long Error Message
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The long error message is intended to inform the human reader about an
   error that has occurred.
<P>
 
   You may supply a character string of length up to 1840 characters as the
   input argument to <a href="../cspice/setmsg_c.html">setmsg_c</a>. Strictly speaking, the long message is
   optional, but it's recommended that you call <a href="../cspice/setmsg_c.html">setmsg_c</a> before every call
   to <a href="../cspice/sigerr_c.html">sigerr_c</a>, supplying a blank string if you don't wish to set a long
   message.
<P>
 
   As an example, the calls to <a href="../cspice/setmsg_c.html">setmsg_c</a> and <a href="../cspice/sigerr_c.html">sigerr_c</a> from the example in
   the last section are repeated here:
<P>
 
<PRE>
    <a href="../cspice/setmsg_c.html">setmsg_c</a> ( "DACOSH: Invalid argument, X is less than one." );
 
    <a href="../cspice/sigerr_c.html">sigerr_c</a> ( "SPICE(INVALIDARGUMENT)"                        );
</PRE>
   Frequently, one would like to insert variable strings into a long
   message. In the above example, it might be nice to convert X, a double
   precision number, to a character string and put it in the error message.
   CSPICE provides the routine, <a href="../cspice/errdp_c.html">errdp_c</a>, for just this purpose.
<P>
 
   <a href="../cspice/errdp_c.html">errdp_c</a> takes two arguments. The first is a character string to appear
   in the long error message. It marks the place where the result of the
   conversion is to be placed in the long error message.
<P>
 
   The second argument is the value to be converted to a character string.
   The resulting string is substituted for the first occurrence of the
   first argument found in the long message.
<P>
 
   Here's the previous example, re-written using ERRDP.
<P>
 
<PRE>
      /*
      Set long error message, with a MARKER where
      the value of X will go.  Our marker is '#'.
      */
 
      <a href="../cspice/setmsg_c.html">setmsg_c</a> ( "DACOSH: Invalid argument, x&lt;1.  The value is #.");
 
      /*
      Convert X to characters, and insert the result
      in the long message where the # is now:
      */
      <a href="../cspice/errdp_c.html">errdp_c</a> ( "#",  x );
 
 
      /*
      If x happened to be -5.5D0, for example, the long message
      becomes:
 
      "DACOSH: Invalid argument, x &lt; 1.  The value is -5.5D0."
 
 
      Signal the error:
      */
      <a href="../cspice/sigerr_c.html">sigerr_c</a> ( "SPICE(INVALIDARGUMENT)" );
</PRE>
   In addition to <a href="../cspice/errdp_c.html">errdp_c</a>, errint_c and <a href="../cspice/errch_c.html">errch_c</a> are provided for inserting
   integers and character strings into the long message.
<P>
 
<BR><BR>
<A NAME="Using the RETURN Action and the CSPICE Function, return_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Using the RETURN Action and the CSPICE Function, <a href="../cspice/return_c.html">return_c</a>
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   If you want your program to do any error handling in addition to
   CSPICE's automatic error handling, you probably would like to prevent
   your program from crashing as a result of an error, since this
   unfortunate event may prevent control from ever being given to your
   error handling code.
<P>
 
   CSPICE solves this problem with the boolean function <a href="../cspice/return_c.html">return_c</a>, and the
   RETURN error response action.
<P>
 
   The first two lines of executable code of every CSPICE routine that can
   detect errors, or that calls another routine, are:
<P>
 
<PRE>
   if ( <a href="../cspice/return_c.html">return_c</a> () )
      {
      return;
      }
</PRE>
   When the error action is RETURN and an error has been signaled, <a href="../cspice/return_c.html">return_c</a>
   takes the `true' value. So every CSPICE routine that can detect errors,
   or that calls another routine, returns without doing anything. This
   greatly reduces the chance of an error causing a program crash.
<P>
 
   You can use the function <a href="../cspice/return_c.html">return_c</a> in your own code to achieve the same
   effect.
<P>
 
   <a href="../cspice/return_c.html">return_c</a> always takes the `false' value if the error action is not
   RETURN.
<P>
 
   See the next section to find out what the rest of the IF block should
   be.
<P>
 
<BR><BR>
<A NAME="Maintaining Traceback Information -- Checking In and Checking Out"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Maintaining Traceback Information -- Checking In and Checking Out
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   CSPICE can give you a ``picture'' of your call chain at the time an
   error is signaled, and at any time before. We call this a ``traceback.''
   A traceback is provided in the default selection of error messages. When
   an error is signaled, a traceback helps you find out what calls were
   made before the call to the routine which detected an error.
<P>
 
   As an example, suppose the following figure shows the calling hierarchy
   for a program, and that currently, subroutine ``E'' is executing, after
   being called by ``C.''
<P>
 
<PRE>
 
        MAIN
      /  |  \
     B   C   D
    / \ /|   |
   E   F E   H
 
</PRE>
   The active call chain would consist of ``MAIN,'' ``C,'' and ``E.'' The
   traceback message, if retrieved at this point, would be:
<P>
 
<PRE>
   MAIN --&gt; C --&gt; E
</PRE>
   To make your own code participate in the traceback scheme, every routine
   in your program (except those that call nothing else and don't detect
   errors) should ``check in'' on entry and ``check out'' on exit. These
   actions tell the error handling mechanism whether your routine is in the
   active call chain or not.
<P>
 
   To check in, call <a href="../cspice/chkin_c.html">chkin_c</a>, supplying the name of your routine. To check
   out, call <a href="../cspice/chkout_c.html">chkout_c</a>, also supplying the name of your routine. The call to
   <a href="../cspice/chkin_c.html">chkin_c</a> should come immediately after each entry into your code. A call
   to <a href="../cspice/chkout_c.html">chkout_c</a> should precede each exit made after checking in. For
   example:
<P>
 
<PRE>
      /*
      Here's a skeleton of code for a mock routine, suba:
 
      Executable code follows
      */
 
      if ( <a href="../cspice/return_c.html">return_c</a>() )
         {
 
         /* No check out here, since we haven't checked in. */
         return;
 
         }
      else
         {
         <a href="../cspice/chkin_c.html">chkin_c</a> ( "suba" );
         }
 
               .
               .
               .
 
      if ( x &lt; 1. )
         {
 
         /* First exit following check in: */
         <a href="../cspice/chkout_c.html">chkout_c</a> ( "suba" );
         return;
         }
               .
               .
               .
 
      /* Normal exit: */
 
      <a href="../cspice/chkout_c.html">chkout_c</a> ( "suba" );
      return;
 
 
</PRE>
   The traceback storage can accommodate a stack depth of 100 routines; the
   maximum length of each stored name is 32 characters.
<P>
 
<BR><BR>
<A NAME="Clean Coding Using failed_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Clean Coding Using <a href="../cspice/failed_c.html">failed_c</a>
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   When you set the action to RETURN, all CSPICE routines that can detect
   errors simply RETURN UPON ENTRY. So, they can't cause a run-time error.
   Therefore, you may safely call a number of CSPICE routines
   consecutively, and just test <a href="../cspice/failed_c.html">failed_c</a> after the last call in the
   sequence.
<P>
 
<BR><BR>
<A NAME="Example 10"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Example 1
</H3><P><BR><BR>
<PRE>
   /*
   Read a line from userfile1.txt, userfile2.txt,
   and userfile3.txt; check for errors:
   */
   <a href="../cspice/rdtext_c.html">rdtext_c</a> ( "userfile1.txt", line1_len, line1, &amp;eof );
   <a href="../cspice/rdtext_c.html">rdtext_c</a> ( "userfile2.txt", line1_len, line2, &amp;eof );
   <a href="../cspice/rdtext_c.html">rdtext_c</a> ( "userfile3.txt", line1_len, line3, &amp;eof );
 
   if (  failed()  )
   {
      /* Not all of line1, line2, line3 are valid, so quit: */
 
      <a href="../cspice/chkout_c.html">chkout_c</a> ( "mysub" );
      return;
   }
</PRE>
<BR><BR>
<A NAME="Example 20"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Example 2
</H3><P><BR><BR>
<PRE>
   /*
   In the following code, copyc is used to copy the result
   of the union of two sets (ordered cells) from a temporary
   working set back into one of the original sets.
   */
   <a href="../cspice/union_c.html">union_c</a>( &amp;bod,  &amp;planets, &amp;temp );
   <a href="../cspice/copy_c.html">copy_c</a> ( &amp;temp, &amp;bod );
 
   if ( <a href="../cspice/failed_c.html">failed_c</a>() )
   {
      <a href="../cspice/chkout_c.html">chkout_c</a> ( "mysub" );
      return;
   }
   /*
   If the size of the temporary cell is greater than the size
   of the original set, <a href="../cspice/failed_c.html">failed_c</a>() should be checked to be
   sure that no overflow occurred. If bodies is at least as
   large as temp, no such check is necessary.
   */
</PRE>
   You can also use this coding technique with calls to your own routines,
   if your use the function <a href="../cspice/return_c.html">return_c</a>.
<P>
 
<BR><BR>
<A NAME="Finding Out What the Current Error Handling Settings Are"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Finding Out What the Current Error Handling Settings Are
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Below we explain how to set the error output device, the selection of
   error messages to output, and the error response action. You can
   retrieve the current settings of these items by calling the same
   routines you used to choose the settings, supplying the value ``GET'' as
   the first argument, instead of 'SET'.
<P>
 
   For example, you find out which device error output is sent to:
<P>
 
<PRE>
   <a href="../cspice/errdev_c.html">errdev_c</a> ( "GET", lenout, device );
 
   /*
   device, with length lenout, now contains the name of the
   output device.
   */
</PRE>
   To find out what the current error response action is:
<P>
 
<PRE>
   <a href="../cspice/erract_c.html">erract_c</a> ( "GET", lenout, action );
 
   /*
   action, with length lenout, now contains the current error
   response action.
   */
</PRE>
   To find out what the current error message selection is:
<P>
 
<PRE>
   <a href="../cspice/errprt_c.html">errprt_c</a> ( "GET", lenout, list );
 
   /*
   list now contains the last list of messages that
   was input by a call to <a href="../cspice/errprt_c.html">errprt_c</a>.  If no call was made,
   list has the value "DEFAULT".
   */
</PRE>
<BR><BR>
<A NAME="Concepts and Definitions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Concepts and Definitions
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="About Errors"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> About Errors
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   What do we mean by ``errors''? In general, we mean ``asking routines to
   do something they can't do.'' Examples include supplying invalid values
   of input arguments to a subroutine, exceeding program limits such as the
   maximum number of files open simultaneously, or trying to read from a
   file that doesn't exist.
<P>
 
   When an error is detected because a routine has been used improperly,
   information about the context of the error is desirable. It's useful to
   know in which routine the error was detected, what the call chain was at
   the time of the error, and what the inputs to the routine that detected
   the error were. The CSPICE error handling mechanism is designed to
   provide this type of information.
<P>
 
   On the other hand, when it's the program's job to determine the
   correctness of data, information about the program is not what is wanted
   when an error occurs. In this case, information about the data is what's
   needed. CSPICE's automatic error handling is not appropriate for dealing
   with this type of error. However, it is possible to shut off the
   automatic error handling, using the IGNORE error action, and use
   non-CSPICE code to handle these errors.
<P>
 
   In general, CSPICE's automatic error handling is most useful for
   diagnosing programming errors.
<P>
 
   The only errors that the CSPICE error handling mechanism deals with are
   DETECTABLE ones. CSPICE can test whether a calling routine has supplied
   an argument that's in the domain of a function, but it can't tell if the
   calling routine has the order of the arguments in a calling sequence
   reversed. By coincidence, an error may be detected in that case, but the
   diagnosis will point to the error in an indirect way, at best. And if an
   application uses a faulty algorithm, but nonetheless uses the CSPICE
   routines correctly, SPICELIB can't tell you about it.
<P>
 
   Some detectable errors exist which CSPICE does not detect. While
   attempted division-by-zero errors are prevented, floating overflow is
   generally not prevented (because doing so is too inefficient).
<P>
 
   When a CSPICE routine detects an error, it may mean the routine is being
   used improperly. One of the most likely causes is an interface error:
   inputs may be supplied to the routine that it can't handle, or there may
   be an error in the coding of the call to the routine itself. It's a good
   idea to thoroughly understand the descriptions of inputs and outputs
   given in the module headers of each CSPICE routine called by one's
   application.
<P>
 
   Some other possible causes of errors may be: bugs in application
   software, bugs in CSPICE software, or bad inputs to the application
   program. Errors can also occur due to problems with the program's
   environment. For example, an attempt to open a file could fail because
   the application program didn't have the privileges necessary to perform
   the open, or on some systems, because the file was in use by another
   user.
<P>
 
<BR><BR>
<A NAME="About Error Messages"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> About Error Messages
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   CSPICE uses error messages to inform both the application program using
   CSPICE, and the user, about what type of error has occurred and where in
   the program it occurred.
<P>
 
   CSPICE provides routines for setting and retrieving error messages. When
   a routine detects an error, it may ``set,'' or store, error messages,
   which then can be retrieved and examined by other routines.
<P>
 
   There are five types of error messages:
<P>
 
<UL>
<TT>--</TT> The short error message.
<BR><BR></UL>
<UL>
<TT>--</TT> The explanation of the short error message.
<BR><BR></UL>
<UL>
<TT>--</TT> The long error message.
<BR><BR></UL>
<UL>
<TT>--</TT> Traceback.
<BR><BR></UL>
<UL>
<TT>--</TT> The default message.
<BR><BR></UL>
<BR><BR>
<A NAME="The short error message"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The short error message
</H3><P><BR><BR>
   This message is a character string containing a very terse, usually
   abbreviated, description of the problem. The message is a character
   string of length not more than 25 characters. It always has the form:
<P>
 
<PRE>
    SPICE(...)
</PRE>
   where the message text goes between the parentheses. An example is:
<P>
 
<PRE>
    SPICE(FILEOPENFAILED)
</PRE>
   The text is always composed of upper case letters and numbers.
<P>
 
   Short error messages used in CSPICE are CONSTANT, since they are
   intended to be used in code. That is, they don't contain any data which
   varies with the specific instance of the error they indicate.
<P>
 
   Because of the brief format of the short error messages, it is practical
   to use them in a test to determine which type of error has occurred.
<P>
 
   For example:
<P>
 
<PRE>
   <a href="../cspice/rdtext_c.html">rdtext_c</a> ( file, line_len, line, &amp;eof );
 
   if ( failed()_c )
   {
      /*
      An error occurred.  Find out what the short message was:
      */
      <a href="../cspice/getmsg_c.html">getmsg_c</a> ( "SHORT, shrtms_len, shrtms );
 
      if (    <a href="../cspice/eqstr_c.html">eqstr_c</a>(shrtms, "SPICE(NOFREELOGICALUNIT)" )
           || <a href="../cspice/eqstr_c.html">eqstr_c</a>(shrtms, "SPICE(TOOMANYFILESOPEN)"  )  )
      {
          /* We won't succeed in reading any file. So, quit. */
 
          return;
      }
   }
   else
   {
      .
      .
      .
</PRE>
   If you use the CSPICE error mechanism to respond to errors detected in
   your own code, you may wish to use your own short error messages. The
   CSPICE error handling mechanism doesn't make use of the actual content
   of the messages, so you may use any values that are practical. It may be
   of use to make up your own prefix (analogous to CSPICE's ``SPICE'' ), to
   identify the errors as detected by your own code. Recall the
   25-character limit; excess characters will be truncated.
<P>
 
   We recommend that you do NOT use blank short error messages. While the
   error handling mechanism allows it, the short error messages would no
   longer be useful for enabling code to determine the type of error that
   has occurred.
<P>
 
   The short message is ``set'' by supplying it as an input argument to the
   CSPICE routine <a href="../cspice/sigerr_c.html">sigerr_c</a>. It is retrieved by calling <a href="../cspice/getmsg_c.html">getmsg_c</a> or getsms_.
<P>
 
<BR><BR>
<A NAME="The explanation of the short error message"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The explanation of the short error message
</H3><P><BR><BR>
   An 80-character expansion of the short message exists for a subset of
   CSPICE's short messages. Each explanation message is constant. While the
   short message is meant to be used in code, the explanation is supposed
   to be easily interpreted by the human reader.
<P>
 
   CSPICE provides the routine expln_ to map short error messages to their
   explanations.
<P>
 
   Currently, there is no provision to extend the mapping to user-defined
   short messages.
<P>
 
   In future versions of CSPICE, more space may be allocated for
   explanations. However, expln_ will continue to return the first
   80-character line of the explanation text in that case.
<P>
 
   Here's an example of a short message and the corresponding explanation:
<P>
 
<PRE>
   Short message: "SPICE(ZERORADIUS)"
 
   Explanation:   "Invalid Radius--Equatorial or Polar Radius is Zero"
</PRE>
<BR><BR>
<A NAME="The long error message"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The long error message
</H3><P><BR><BR>
   This message may be up to 1840 characters long. The CSPICE error
   handling mechanism makes no use of its contents. Its purpose is to
   provide human-readable information about errors.
<P>
 
   Long error messages generated by CSPICE routines often contain data
   relevant to the specific error they describe. Here's an example of a
   long error message generated by a misspelled body name provided as an
   input to the CSPICE function <a href="../cspice/spkezr_c.html">spkezr_c</a>:
<P>
 
<PRE>
   The observer, 'earthh', is not a recognized name for an
   ephemeris object. The cause of this problem may be that
   you need an updated version of the SPICE toolkit. Alternatively
   you may call SPKEZ directly if you know the SPICE ID codes
   for both 'moon' and 'earthh'
</PRE>
   The long message is ``set'' by supplying it as an input argument to the
   CSPICE routine <a href="../cspice/setmsg_c.html">setmsg_c</a>. It may be retrieved by calling <a href="../cspice/getmsg_c.html">getmsg_c</a> or
   getlms_.
<P>
 
   The routines, <a href="../cspice/errdp_c.html">errdp_c</a>, errint_c, and <a href="../cspice/errch_c.html">errch_c</a> provide the capability to
   insert data into the long message. Their respective purposes are to
   insert double, int, and char * data into the long message. They (except
   <a href="../cspice/errch_c.html">errch_c</a>) convert the input data to a character string, and insert it in
   the current long message at a location indicated by a user-specified
   marker.
<P>
 
   We strongly recommend that you DO NOT write code that tests for
   particular values of CSPICE long error messages; this is a very
   error-prone practice.
<P>
 
<BR><BR>
<A NAME="The traceback"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The traceback
</H3><P><BR><BR>
   The purpose of this message is to represent the active call chain, that
   is, the set of subroutines in your program that have been called and
   have not yet returned. The traceback will always show the CSPICE
   routines in the active call chain.
<P>
 
   You can have your own code participate in the CSPICE traceback scheme,
   so that the traceback will represent the entire active call chain.
<P>
 
   Knowledge of the active call chain can be a valuable debugging aid,
   because it helps you determine where in your program an error occurred.
   For example, if your program calls subroutine SUBX from ten different
   subroutines, it's not enough to know that SUBX detected an error; you
   want to know which subroutine made the offending call to SUBX. The
   traceback contains that information. Another example: suppose a CSPICE
   routine in your program detects an error, but your own code does not
   call that routine. You need to know which call, made by your own code to
   a CSPICE routine, eventually resulted in the call to the routine that
   detected the error. The traceback shows you this.
<P>
 
   The CSPICE error handling mechanism automatically keeps track of which
   CSPICE routines are in the active call chain. In order for the CSPICE
   error handling mechanism to represent the entire active call chain,
   including non-CSPICE routines, it is necessary for each routine to tell
   the error handling mechanism: 1) when it has been called and 2) when it
   is about to return. In CSPICE documentation, these two operations are
   called ``checking in'' and ``checking out.'' The set of routines that
   have checked in but have not yet checked out constitute the portion of
   the active call chain that the CSPICE error handling mechanism can
   represent.
<P>
 
   CSPICE provides the two routines <a href="../cspice/chkin_c.html">chkin_c</a> and <a href="../cspice/chkout_c.html">chkout_c</a> for this purpose;
   <a href="../cspice/chkin_c.html">chkin_c</a> for checking in, and <a href="../cspice/chkout_c.html">chkout_c</a> for checking out. chkin_c and
   <a href="../cspice/chkout_c.html">chkout_c</a> take one input argument: the name of the calling routine.
<P>
 
   The traceback message has the form of a list of subroutine names,
   delimited by arrows. The first name in the list is the highest-level
   routine in the portion of the active call chain that is known to the
   CSPICE error handling mechanism.
<P>
 
   As an example, suppose the following figure shows the calling hierarchy
   for a program, and that currently, subroutine ``E'' is executing, after
   being called by ``C.''
<P>
 
<PRE>
 
        MAIN
      /  |  \
     B   C   D
    / \ /|   |
   E   F E   H
 
</PRE>
   The active call chain would consist of ``MAIN,'' ``C,'' and ``E.'' The
   traceback message, if retrieved at this point, would be:
<P>
 
<PRE>
   MAIN --&gt; C --&gt; E
</PRE>
   The particular traceback information made available by CSPICE is
   dependent on the error action and on whether an error has occurred. In
   general, the routines qcktrc_, trcdep_, and trcnam_ return information
   about the current active call chain. But when the error response action
   is RETURN, and an error occurs, the error handling mechanism captures a
   ``frozen'' copy of the traceback; from this point on, the trace
   information provided by the above routines will be based on the frozen
   copy. The purpose of this behavior is to make the traceback that existed
   at the time the error occurred available to the application program.
   Changing the error action to a value other than RETURN, or resetting the
   error status, will cause the traceback routines qcktrc_, trcdep_, and
   trcnam_ to return data based on the current traceback again.
<P>
 
   The overhead of checking in and checking out may be prohibitive for some
   routines. An intermediate position between not using <a href="../cspice/chkin_c.html">chkin_c</a> and
   <a href="../cspice/chkout_c.html">chkout_c</a> and using them in every routine is to use them only in routines
   that call other routines, or that detect errors. Routines which do
   neither would never appear in a traceback anyway. Note that absence of
   error detection in a routine is not sufficient grounds for exclusion
   from checking in and checking out, since a routine called by the routine
   in question could detect an error, and then the caller should appear in
   the traceback.
<P>
 
   It is important to note that ONLY routines which have checked in can
   possibly have their names appear in the traceback. So the traceback will
   not be accurate if any routines in the active call chain have not
   ``checked in,'' when a traceback message is produced.
<P>
 
   The traceback mechanism requires any ``checked-in'' routine to check out
   before exit.
<P>
 
<BR><BR>
<A NAME="The default message"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The default message
</H3><P><BR><BR>
   This message is output when an error occurs, and the error response
   action is DEFAULT. It informs the user that the behavior of CSPICE error
   handling is user-tailorable, and it refers the user to this document.
<P>
 
<BR><BR>
<A NAME="About Error Response Actions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> About Error Response Actions
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The term ``error response action'' refers to the action that the CSPICE
   error handling mechanism takes automatically when an error is signaled.
   CSPICE provides the routine <a href="../cspice/erract_c.html">erract_c</a> to enable you to select the error
   response action.
<P>
 
   There are five different error response actions, each appropriate to a
   different type of programming situation:
<P>
 
<DL><DT>
<B>
 DEFAULT
</B><BR><BR>
<DD>
 This is what you get if you don't choose an error response action. When
the error action is DEFAULT, and an error is signaled, the CSPICE error
handling mechanism outputs all of the available types of error messages
to the error output device, and then stops program execution.<BR>
</DL>
   The default action is probably acceptable as a response to detection of
   program bugs. However, if you wish to allow your own program to respond
   to errors, you must choose one of REPORT, RETURN, or IGNORE as the error
   response action.
<P>
 
<DL><DT>
<B>
 ABORT
</B><BR><BR>
<DD>
 This action is the same as the default, except that the set of error
messages is selectable. This action is useful for running programs in
batch mode, to prevent them from continuing execution after
encountering an error. The ABORT action is also useful if your program
does not perform any error handling itself.<BR>
</DL>
<DL><DT>
<B>
 REPORT
</B><BR><BR>
<DD>
 This action can be useful for debugging. With the REPORT action, the
CSPICE error handling mechanism outputs error messages when an error is
signaled, but doesn't stop your program. So, more information can be
gained from a single run of your program than with the ABORT action.
Using the CSPICE routine <a href="../cspice/errdev_c.html">errdev_c</a>, you can direct the error messages
output by the CSPICE error handling mechanism to a file, thus creating
a log of your errors.<BR>
</DL>
   However, the function <a href="../cspice/failed_c.html">failed_c</a> will indicate an error condition after an
   error has been signaled. Therefore, any program logic that depends on
   the value returned by <a href="../cspice/failed_c.html">failed_c</a> may be affected by an error. You can use
   the CSPICE routine <a href="../cspice/reset_c.html">reset_c</a> to set the error status to ``no error,'' so
   that your program will attempt to follow a normal thread of execution,
   after an error is signaled.
<P>
 
<DL><DT>
<B>
 RETURN
</B><BR><BR>
<DD>
 The RETURN action's intend use is in situations where you want your
program to recover from errors detected by CSPICE (or by your own
code). Like the REPORT action, the RETURN action also includes writing
error messages to the chosen output device. But with the RETURN action,
the CSPICE function <a href="../cspice/return_c.html">return_c</a> takes the `true' value when an error is
signaled. Any routine that tests the function <a href="../cspice/return_c.html">return_c</a> on entry, and
that returns immediately if <a href="../cspice/return_c.html">return_c</a> takes the `true' value, will not
crash in this case. All CSPICE routines that can detect errors, or that
call other routines, do test <a href="../cspice/return_c.html">return_c</a> on entry and return if the `true'
value. This behavior maximizes the chance that CSPICE routines will
return control to the application program using them, in the event of
an error.<BR>
</DL>
   It is also possible to use the function <a href="../cspice/return_c.html">return_c</a> in the same way in your
   own routines. We note here that use of <a href="../cspice/return_c.html">return_c</a> mode allows you to call
   multiple CSPICE routines consecutively, without testing the error status
   until after the last call. This can greatly enhance the readability of
   your code, and increase its efficiency, as well.
<P>
 
   Returning control to the non CSPICE portion of the program allows for a
   response to the error condition. The nature of the response is
   application-dependent. However, in the case that the error does not
   preclude further successful operation of the program, it is necessary to
   instruct the CSPICE error handling mechanism that normal operation is
   desired, after the error has been responded to. The CSPICE function
   RESET is provided for this purpose. Calling RESET blanks out all stored
   error messages, and causes the functions FAILED and <a href="../cspice/return_c.html">return_c</a> to take the
   `false' value.
<P>
 
<DL><DT>
<B>
 IGNORE
</B><BR><BR>
<DD>
 This action is provided to allow you to completely ``shut off''
CSPICE's automatic error handling. When this action is selected, and
any routine signals an error, no action is taken by the CSPICE error
handling mechanism. The error messages cannot be updated by <a href="../cspice/sigerr_c.html">sigerr_c</a>
and <a href="../cspice/setmsg_c.html">setmsg_c</a>, and <a href="../cspice/return_c.html">return_c</a> and FAILED will not change their values.<BR>
</DL>
   This action may be useful in the case where you know exactly which
   errors will be detected by CSPICE routines, and you know that no
   response is required.
<P>
 
   Note that the IGNORE action is not appropriate for the case where you
   wish to suppress automatic output of CSPICE error messages, and to
   handle CSPICE errors in your own code. To do that, use the RETURN error
   action and set the selection of error messages to 'NONE', using
   <a href="../cspice/errprt_c.html">errprt_c</a>.
<P>
 
<BR><BR>
<A NAME="Advanced Programming with Error Handling"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Advanced Programming with Error Handling
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   This chapter discusses some further error handling topics.
<P>
 
<BR><BR>
<A NAME="Using the CSPICE Functions failed_c and return_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Using the CSPICE Functions <a href="../cspice/failed_c.html">failed_c</a> and <a href="../cspice/return_c.html">return_c</a>
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   First, note that the CSPICE function <a href="../cspice/return_c.html">return_c</a> takes the `false' value
   unless the error response action is RETURN, so all of the following
   discussion assumes that the error action has been set to RETURN.
<P>
 
   Which routines should use the function <a href="../cspice/return_c.html">return_c</a>, and where?
<P>
 
   The ``which?'' question is somewhat tricky: there's a trade-off between
   speed and resistance to program crashes. It takes time (not much) to
   test <a href="../cspice/return_c.html">return_c</a>, and in a very short routine, such as one that computes a
   dot product, the execution time can be increased by a substantial factor
   if <a href="../cspice/return_c.html">return_c</a> is tested. In most routines, the percentage increase in
   execution time is small.
<P>
 
   So, if you don't want to test <a href="../cspice/return_c.html">return_c</a> in every routine, how do you
   decide? The CSPICE answer to this question is, test <a href="../cspice/return_c.html">return_c</a> in routines
   that call other routines or detect errors (CSPICE routines that are
   specifically intended to perform error handling are exempt from testing
   <a href="../cspice/return_c.html">return_c</a>). If a routine calls another routine already, it's unlikely
   that testing <a href="../cspice/return_c.html">return_c</a> will slow its execution intolerably. Similarly for
   routines that test for error conditions.
<P>
 
   Our final answer is still a hedge: the proper use of <a href="../cspice/return_c.html">return_c</a> depends on
   your speed and reliability requirements. The CSPICE method may be a good
   zero-order approximation to what's optimal.
<P>
 
   NOTE: You must be very careful about using <a href="../cspice/return_c.html">return_c</a> in application code
   that DOES error handling, otherwise your error handling code itself may
   not function when an error is signaled.
<P>
 
   The ``where?'' question also eludes a straightforward answer. The idea
   behind the RETURN action is to ensure that control is returned to
   whatever part of your program handles errors, when an error is signaled.
   According to this idea, once an error has been signaled, you have to do
   something about the error before you can finish the job. So, routines
   that do use <a href="../cspice/return_c.html">return_c</a> ought to test it at the very beginning of their
   executable code; there's no reason for them to proceed further until the
   error condition has been acted upon.
<P>
 
   What about using the function <a href="../cspice/return_c.html">return_c</a> in other parts of the code, for
   instance following calls to CSPICE routines? The same speed vs crash
   resistance trade-off applies, but there is another consideration:
   <a href="../cspice/return_c.html">return_c</a> has an effect only when the error action is RETURN. So, in
   cases where an error condition makes it likely that a portion of code
   won't work, it's usually better to test the function <a href="../cspice/failed_c.html">failed_c</a>, rather
   than <a href="../cspice/return_c.html">return_c</a>, since a program crash is usually undesirable, even when
   using the REPORT action for debugging. But if you do want to retain the
   option of executing the code when an error has already occurred, use
   <a href="../cspice/return_c.html">return_c</a>.
<P>
 
   We repeat here that the CSPICE function <a href="../cspice/failed_c.html">failed_c</a> indicates whether an
   error has been signaled, regardless of the error response action. It can
   be used to avoid executing any code that may cause a run-time error if
   an error has already occurred. Note that testing <a href="../cspice/failed_c.html">failed_c</a> instead of
   <a href="../cspice/return_c.html">return_c</a> means that whether the error response action is RETURN or
   REPORT doesn't affect the program logic in question; the logic depends
   on whether or not an error has been signaled.
<P>
 
<BR><BR>
<A NAME="Using the CSPICE routines chkin_c and chkout_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Using the CSPICE routines <a href="../cspice/chkin_c.html">chkin_c</a> and <a href="../cspice/chkout_c.html">chkout_c</a>
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The simplest approach to the use of these routines is to use them in
   every routine you write. But as with the case of <a href="../cspice/return_c.html">return_c</a>, your routines
   will be slightly slower if they call <a href="../cspice/chkin_c.html">chkin_c</a> and <a href="../cspice/chkout_c.html">chkout_c</a>, and for very
   short routines, the percentage difference may be great.
<P>
 
   The CSPICE approach is to call <a href="../cspice/chkin_c.html">chkin_c</a> and <a href="../cspice/chkout_c.html">chkout_c</a> in routines which
   call other routines or which can detect errors. This way, every routine
   that can possibly be in the active call chain at the time an error is
   detected can appear in the traceback message.
<P>
 
   As mentioned in the previous section, these routines are less likely to
   suffer a large percentage increase in execution time as a result of
   making extra calls.
<P>
 
   We note that some routines that do make external references but do not
   signal errors may have no routines capable of signaling errors below
   them in the calling hierarchy; these routines won't appear in a
   traceback. Why should they call <a href="../cspice/chkin_c.html">chkin_c</a> and <a href="../cspice/chkout_c.html">chkout_c</a>? They should do so
   for maintenance reasons, specifically, if any routine below them in the
   calling hierarchy is changed so as to be able to detect an error, the
   higher level routines don't need to be changed.
<P>
 
<BR><BR>
<A NAME="Using Multiple Settings of the Automatic Error Handling Features"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Using Multiple Settings of the Automatic Error Handling Features
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In the second chapter, we suggested that you choose the error output
   device, error response action, and selection of error messages, during
   program initialization and leave them unchanged for the duration of the
   program run. This is probably a good procedure to stick to for
   inexperienced users. However, it's possible and reasonable to do some
   fancier things with these settings, in some cases:
<P>
 
<UL>
<TT>--</TT> Resetting the output device. This isn't particularly fancy; you may simply
want to write error messages from different parts of your program to
different devices. <a href="../cspice/errdev_c.html">errdev_c</a> may be called from anywhere in your program, as
many times as your wish. Note that the error response action should not be
DEFAULT or ABORT, for in this case the first error signaled terminates
execution.
<BR><BR></UL>
<UL>
<TT>--</TT> Resetting the error message selection. Nothing to it, just call <a href="../cspice/errprt_c.html">errprt_c</a>
any time. Again, note that the error response action should not be DEFAULT
or ABORT, for in this case the first error signaled terminates execution.
<BR><BR></UL>
<UL>
<TT>--</TT> Resetting the error response action. <a href="../cspice/erract_c.html">erract_c</a> can also be called at any
time. However, it is important to be aware of the special effects of these
error response action ``transitions.'' Specifically:
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> When making a transition to a new action, the value of <a href="../cspice/failed_c.html">failed_c</a> does not
change. If <a href="../cspice/failed_c.html">failed_c</a> has the `true' value, and you set the action to IGNORE,
any NEW errors that are signaled will be ignored, but <a href="../cspice/failed_c.html">failed_c</a> will remain
`true'.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> The value of the function <a href="../cspice/return_c.html">return_c</a> depends on FAILED and the current
action. Specifically, <a href="../cspice/return_c.html">return_c</a> has the `true' value if and only if <a href="../cspice/failed_c.html">failed_c</a>
has the `true' value and the action is RETURN. Therefore, note that if
<a href="../cspice/failed_c.html">failed_c</a> has the `true' value and you change the action to RETURN, the
function RETURN will now have the `true' value, regardless of its previous
value. Setting the action to something other than RETURN will cause
<a href="../cspice/return_c.html">return_c</a> to take the `false' value, regardless of its previous value.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Changing the error action doesn't affect the stored short and long error
messages, if any. If there are stored messages, they will still be
available if the action is changed to IGNORE.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> The traceback routines return information about the ``frozen'' traceback if
and only if <a href="../cspice/return_c.html">return_c</a> has the `true' value. So the rule about which
traceback you get is the same as the rule for the value of <a href="../cspice/return_c.html">return_c</a>.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Changing the action to ABORT or DEFAULT doesn't automatically abort your
program if FAILED has the `true' value; an error must be signaled while the
action is one of these values to achieve an abort.
<BR><BR></UL>
<UL>
<TT>--</TT> Temporary resetting of the error handling selections. What if you want to
set the error action to ABORT or IGNORE while a certain section of code
executes, and then set it back to its original value? Easy: call <a href="../cspice/erract_c.html">erract_c</a>
with the ``GET'' option to get the current error action. Save this value,
call <a href="../cspice/erract_c.html">erract_c</a> with the ``SET'' option to set the new value, and finally set
the action back to the saved value.
<BR><BR></UL>
   For example:
<P>
 
<PRE>
   /*
   All errors in the following section of code are
   fatal.  Temporarily set the error action to
   "ABORT"; restore old action after end of code
   section.
   */
 
   <a href="../cspice/erract_c.html">erract_c</a> ( "GET", len_savact, savact  );
 
   <a href="../cspice/erract_c.html">erract_c</a> ( "SET", len_savact, "ABORT" );
 
 
    { Section of code in which errors are fatal starts here }
 
                          .
                          .
                          .
 
 
    { Section of code in which errors are fatal ends here }
 
 
   /*
   Restore old error action:
   */
   <a href="../cspice/erract_c.html">erract_c</a> ( "SET", len_savact, savact );
</PRE>
   Changes to the error output device or error message selection can be
   made in the same way; both <a href="../cspice/errdev_c.html">errdev_c</a> and <a href="../cspice/errprt_c.html">errprt_c</a> accept the values
   ``GET'' and ``SET'' for their first argument.
<P>
 

</TD>
</TR>
</TBODY>
</TABLE>

</BODY>

</HTML>
